feat: add /speckit.converge command#3001
Conversation
There was a problem hiding this comment.
Pull request overview
Adds a new core /speckit.converge command template intended to run after /speckit.implement, and wires it into the CLI’s core-command registries, onboarding guidance, and integration test matrices. The PR also includes full spec-driven design artifacts for the converge feature and updates several bundled Spec Kit workflow/extension assets.
Changes:
- Add
templates/commands/converge.mddefining the converge command’s hook handling, intent inventory, findings classification, and append-only tasks contract. - Register
convergeacross core-command enumerations, onboarding “Next Steps”, and integration tests for markdown/toml/yaml/skills and Copilot. - Add SDD artifacts under
specs/001-converge-command/plus bundled.specify/workflow/extension materials and related agent/prompt files.
Show a summary per file
| File | Description |
|---|---|
| tests/integrations/test_integration_generic.py | Updates generic integration expectations to include converge. |
| tests/integrations/test_integration_copilot.py | Updates Copilot integration tests to include converge in core command inventories. |
| tests/integrations/test_integration_base_yaml.py | Adds converge to YAML integration command expectations. |
| tests/integrations/test_integration_base_toml.py | Adds converge to TOML integration command expectations. |
| tests/integrations/test_integration_base_skills.py | Adds converge to skills-based integration command expectations. |
| tests/integrations/test_integration_base_markdown.py | Adds converge to markdown integration command expectations. |
| templates/commands/converge.md | New converge command template defining append-only convergence behavior and hooks. |
| src/specify_cli/integrations/claude/init.py | Adds a Claude argument hint for the converge command. |
| src/specify_cli/extensions.py | Extends fallback core command name set to include converge. |
| src/specify_cli/commands/init.py | Adds converge to post-init “Next Steps” guidance after implement. |
| src/specify_cli/init.py | Adds converge to SKILL_DESCRIPTIONS. |
| specs/001-converge-command/spec.md | New converge feature specification. |
| specs/001-converge-command/research.md | Research decisions/rationale for converge design. |
| specs/001-converge-command/quickstart.md | Manual validation quickstart for converge scenarios. |
| specs/001-converge-command/plan.md | Implementation plan for converge feature rollout. |
| specs/001-converge-command/data-model.md | Conceptual entities for converge findings/tasks/results. |
| specs/001-converge-command/contracts/tasks-output.md | Contract for append format in tasks.md. |
| specs/001-converge-command/contracts/hooks.md | Contract for before_converge / after_converge hooks. |
| specs/001-converge-command/contracts/command-interface.md | Invocation/precondition/output contract for /speckit.converge. |
| specs/001-converge-command/checklists/requirements.md | Spec quality checklist for the converge feature spec. |
| README.md | Adds /speckit.converge to Core Commands table. |
| .specify/workflows/workflow-registry.json | Adds/records bundled workflow registry metadata. |
| .specify/workflows/speckit/workflow.yml | Adds/records bundled “Full SDD Cycle” workflow definition. |
| .specify/templates/tasks-template.md | Adds bundled tasks template content. |
| .specify/templates/spec-template.md | Adds bundled spec template content. |
| .specify/templates/plan-template.md | Adds bundled plan template content. |
| .specify/templates/constitution-template.md | Adds bundled constitution template content. |
| .specify/templates/checklist-template.md | Adds bundled checklist template content. |
| .specify/scripts/bash/setup-tasks.sh | Adds bundled script for resolving task template + available docs. |
| .specify/scripts/bash/setup-plan.sh | Adds bundled plan setup script. |
| .specify/scripts/bash/create-new-feature.sh | Adds bundled feature directory/branch naming script. |
| .specify/scripts/bash/check-prerequisites.sh | Adds bundled prerequisite/path resolution script. |
| .specify/memory/constitution.md | Adds a ratified Spec Kit constitution for governance constraints. |
| .specify/integrations/speckit.manifest.json | Adds/updates speckit integration manifest tracking managed files. |
| .specify/integrations/copilot.manifest.json | Adds/updates copilot integration manifest tracking managed files. |
| .specify/integration.json | Adds/updates repo integration state metadata. |
| .specify/init-options.json | Adds/updates repo init-options metadata. |
| .specify/feature.json | Adds/updates active feature pointer metadata. |
| .specify/extensions/bug/README.md | Adds bundled “bug triage workflow” extension documentation. |
| .specify/extensions/bug/extension.yml | Adds bundled “bug” extension manifest. |
| .specify/extensions/bug/commands/speckit.bug.test.md | Adds bundled speckit.bug.test extension command template. |
| .specify/extensions/bug/commands/speckit.bug.fix.md | Adds bundled speckit.bug.fix extension command template. |
| .specify/extensions/bug/commands/speckit.bug.assess.md | Adds bundled speckit.bug.assess extension command template. |
| .specify/extensions/agent-context/scripts/powershell/update-agent-context.ps1 | Adds/updates bundled PowerShell context upsert script. |
| .specify/extensions/agent-context/scripts/bash/update-agent-context.sh | Adds/updates bundled Bash context upsert script. |
| .specify/extensions/agent-context/README.md | Adds bundled “agent-context” extension documentation. |
| .specify/extensions/agent-context/extension.yml | Adds bundled “agent-context” extension manifest. |
| .specify/extensions/agent-context/commands/speckit.agent-context.update.md | Adds bundled speckit.agent-context.update command template. |
| .specify/extensions/agent-context/agent-context-config.yml | Adds bundled agent-context configuration. |
| .specify/extensions/.registry | Adds/updates bundled extension registry state. |
| .specify/extensions.yml | Adds/updates bundled extensions configuration. |
| .specify/bugs/integration-key-cli-check/test.md | Adds bug workflow verification report artifact. |
| .specify/bugs/integration-key-cli-check/fix.md | Adds bug workflow fix report artifact. |
| .specify/bugs/integration-key-cli-check/assessment.md | Adds bug workflow assessment report artifact. |
| .github/prompts/speckit.taskstoissues.prompt.md | Adds/updates Copilot prompt stub for taskstoissues agent. |
| .github/prompts/speckit.tasks.prompt.md | Adds/updates Copilot prompt stub for tasks agent. |
| .github/prompts/speckit.specify.prompt.md | Adds/updates Copilot prompt stub for specify agent. |
| .github/prompts/speckit.plan.prompt.md | Adds/updates Copilot prompt stub for plan agent. |
| .github/prompts/speckit.implement.prompt.md | Adds/updates Copilot prompt stub for implement agent. |
| .github/prompts/speckit.constitution.prompt.md | Adds/updates Copilot prompt stub for constitution agent. |
| .github/prompts/speckit.clarify.prompt.md | Adds/updates Copilot prompt stub for clarify agent. |
| .github/prompts/speckit.checklist.prompt.md | Adds/updates Copilot prompt stub for checklist agent. |
| .github/prompts/speckit.bug.test.prompt.md | Adds/updates Copilot prompt stub for bug.test agent. |
| .github/prompts/speckit.bug.fix.prompt.md | Adds/updates Copilot prompt stub for bug.fix agent. |
| .github/prompts/speckit.bug.assess.prompt.md | Adds/updates Copilot prompt stub for bug.assess agent. |
| .github/prompts/speckit.analyze.prompt.md | Adds/updates Copilot prompt stub for analyze agent. |
| .github/prompts/speckit.agent-context.update.prompt.md | Adds/updates Copilot prompt stub for agent-context.update agent. |
| .github/copilot-instructions.md | Adds/updates managed Spec Kit context section for Copilot instructions. |
| .github/agents/speckit.taskstoissues.agent.md | Adds/updates Copilot agent command for taskstoissues. |
| .github/agents/speckit.tasks.agent.md | Adds/updates Copilot agent command for tasks. |
| .github/agents/speckit.plan.agent.md | Adds/updates Copilot agent command for plan. |
| .github/agents/speckit.implement.agent.md | Adds/updates Copilot agent command for implement. |
| .github/agents/speckit.constitution.agent.md | Adds/updates Copilot agent command for constitution. |
| .github/agents/speckit.bug.test.agent.md | Adds/updates Copilot agent command for bug.test. |
| .github/agents/speckit.bug.fix.agent.md | Adds/updates Copilot agent command for bug.fix. |
| .github/agents/speckit.bug.assess.agent.md | Adds/updates Copilot agent command for bug.assess. |
| .github/agents/speckit.analyze.agent.md | Adds/updates Copilot agent command for analyze. |
| .github/agents/speckit.agent-context.update.agent.md | Adds/updates Copilot agent command for agent-context.update. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 83/83 changed files
- Comments generated: 2
Dogfood the converge feature through Spec Kit's own workflow: - spec.md, plan.md, tasks.md, research, data-model, contracts, quickstart - requirements checklist for the feature - ratified constitution v1.0.0 (.specify/memory) - Specify project scaffolding (.specify/, .github agent + prompt files) Defines a built-in /speckit.converge command that assesses spec/plan/tasks against the codebase and appends remaining work as new tasks (no git, no change tracking, append-only). Implementation not yet started. Excludes unrelated working-tree changes to agents.py, extensions.py, test_extensions.py, catalog.community.json, and README.md.
Add the built-in converge command that assesses the codebase against a feature's spec.md, plan.md, and tasks.md and appends remaining unbuilt work as new traceable tasks to tasks.md (append-only; no git, no change tracking). - templates/commands/converge.md: full command body (load artifacts, assess code, classify findings missing/partial/contradicts/unrequested, append '## Phase N — Convergence' tasks with source-ref + gap-type, read-only guardrails, converged branch, handoff, before/after_converge hooks) - Register converge as a core command across all enumeration sites (SKILL_DESCRIPTIONS, _FALLBACK_CORE_COMMAND_NAMES, ARGUMENT_HINTS, and the integration test command lists incl. copilot/generic file inventories) - init.py Next Steps panel + README Core Commands table - tasks.md: T001-T024 complete (T025 manual quickstart pending) Full suite green: 2343 passed.
All six quickstart scenarios validated (GitHub Copilot agent, macOS/zsh): S1 gap->appended traceable task, S2 implement+re-converge, S3 converged leaves tasks.md unchanged, S4 read-only boundaries, S5 missing-prereq stop, S6 cross- integration install (copilot + windsurf). Automated suite: 2343 passed.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Two upgrade-path bugs surfaced during converge E2E validation:
- copilot upgrade stale-deleted .vscode/settings.json because setup() only tracks the file when it creates it; on upgrade the pre-existing file is merged and left untracked, so Phase 2 stale cleanup removed it. Add an integration-level stale_cleanup_exclusions() hook (CopilotIntegration returns {.vscode/settings.json}) and subtract it from stale_keys.
- shared .specify/scripts/*.sh lost their execute bit because the managed refresh rewrites them with the bundled source mode (often 0o644) and nothing restored perms. Call ensure_executable_scripts() after the managed-refresh block (POSIX only).
Add regression tests in TestIntegrationUpgrade covering both fixes (validated to fail without the fixes).
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Remove .specify state files that are per-project runtime artifacts: - feature.json, init-options.json, integration.json - manifest files, extension registry, bug artifacts These are generated by 'specify init' and should not be committed. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Add speckit.converge Copilot agent and prompt files (github#3003) - Add regression test for Claude argument hints (github#3005) - Remove invalid converge entry from Claude argument hints - Fix documentation removing branch-prefix fallback claims Supersedes: github#3003, github#3005 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
678d4d4 to
353c0cb
Compare
PR Stack Consolidation SummaryThis PR now contains the complete, clean converge command implementation. Changes from side PRs #3003 and #3005 have been folded in, and those PRs are closed as superseded. Folded from #3003
Folded from #3005
Cleanup
Validation
Posted on behalf of @BenBtg by GitHub Copilot (model: Claude Opus 4.6). |
| ```text | ||
| $ARGUMENTS | ||
| ```text |
Remove .specify/ artifacts, non-converge .github/agents and prompts, and copilot-instructions.md that were generated by 'specify init' and are not part of the converge command feature. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Remove specs/001-converge-command/ — the spec/plan/tasks/research SDD artifacts produced while building this feature. spec-kit does not track a specs/ directory on main (those are outputs of running the workflow on the repo, not part of the shipped tool). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Remove .github/agents/speckit.converge.agent.md and
.github/prompts/speckit.converge.prompt.md — these are generated by
'specify init --integration copilot' from templates/commands/converge.md
(all __SPECKIT_COMMAND_*__/{SCRIPT} tokens are resolved). main tracks no
.github/agents or .github/prompts files; the template is the source of truth.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Move the stale_cleanup_exclusions / executable-bit upgrade fix (base.py, copilot, _migrate_commands.py, test_integration_subcommand.py) out of this PR into its own change. This PR is now scoped purely to the /speckit.converge command. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
| SKILL_DESCRIPTIONS = { | ||
| "specify": "Create or update feature specifications from natural language descriptions.", | ||
| "plan": "Generate technical implementation plans from feature specifications.", | ||
| "tasks": "Break down implementation plans into actionable task lists.", | ||
| "implement": "Execute all tasks from the task breakdown to build the feature.", | ||
| "converge": "Assess the codebase against spec.md, plan.md, and tasks.md and append remaining work as new tasks.", | ||
| "analyze": "Perform cross-artifact consistency analysis across spec.md, plan.md, and tasks.md.", |
There was a problem hiding this comment.
Fixed in 3e00e02. Added converge to _CORE_COMMAND_TEMPLATE_ORDER in src/specify_cli/integrations/base.py (after implement) so it gets an explicit core rank instead of fallback sorting.
converge is a core command in SKILL_DESCRIPTIONS but was missing from _CORE_COMMAND_TEMPLATE_ORDER, so it sorted with the fallback rank. Add it after 'implement' to keep core-command ordering consistent across integrations. Addresses review feedback on github#3001. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
Addressed automated review feedback (commit 3e00e02). Review #4516766070 — fixed: Review #4516276868 (80-file review, predates the PR cleanup) — all 11 comments flag a fence closed with No remaining action from either review. Posted on behalf of @BenBtg by GitHub Copilot (model: Claude Opus 4.8). |
Replace the self-referential sample evidence text in the Convergence Findings table with a neutral placeholder so agents are less likely to copy nonsensical template-specific findings into real output. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
|
||
| | ID | Gap Type | Severity | Source | Evidence | Remaining Work | | ||
| |----|----------|----------|--------|----------|----------------| | ||
| | F1 | missing | HIGH | FR-008 | Required append-only guardrail is not implemented in the assessed command flow | Add append-only enforcement | |
Description
Adds a built-in
/speckit.convergecommand — an implementation-convergence step that runs after/speckit.implement. It reads a feature'sspec.md,plan.md, andtasks.mdas the sole source of intent (with the constitution as governing constraints), assesses the current codebase, and appends remaining unbuilt work as new, traceable tasks totasks.mdso/speckit.implementcan complete it.It is needed to close the gap between what a feature specifies and what the implementation pass actually built, expressed as actionable tasks the existing workflow can consume — without a manual review step.
The command is delivered as a Markdown command template (
templates/commands/converge.md) plus registration of the new core command across the integration registries, integration tests, post-init guidance, and the README Core Commands table.Key behaviours
spec.md,plan.md, existing tasks, or application code. The only write is a new## Phase N — Convergencesection intasks.md.source-ref(e.g.FR-003,SC-002,US1/AC2,Constitution II) and a gap-type label (missing/partial/contradicts/unrequested).convergedresult with summary counts and leavestasks.mdbyte-for-byte unchanged.plan.mdortasks.mdis missing.implement. Hooks:before_converge/after_converge(the latter receives theconvergedvstasks_appendedoutcome).The feature was built through the spec-driven workflow (specify → plan → tasks → implement). Artifacts that are outputs of running the workflow — the
specs/SDD documents and the generated per-agent command files under.github/agents/and.github/prompts/— are intentionally not committed;maintracks none of them. The source of truth for the command istemplates/commands/converge.md, from which each agent's command files are generated byspecify init.PR consolidation
This is the single canonical PR for the converge feature. Useful changes from side PRs #3003 and #3005 were folded in, and those PRs were closed as superseded:
/speckit.convergeoutputs in Copilot integration manifest #3003: documentation fixes removing the incorrect branch-prefix fallback claim (feature resolution uses onlySPECIFY_FEATURE_DIRECTORYand.specify/feature.json). Track/speckit.convergeoutputs in Copilot integration manifest #3003's manifest tracking of generated Copilot command files was not adopted — spec-kit does not commit generated command files.convergeskill against unsupported argument hints #3005: Claude regression test ensuringconvergedoes not advertise an unsupported feature-name argument hint; the invalidconvergeentry was removed from Claude argument hints.specify initscaffolding (.specify/templates/scripts/extensions, unrelated agent/prompt files), the generated Copilot converge command files (.github/agents/,.github/prompts/), and thespecs/001-converge-command/SDD artifacts. Rebased onmain.stale_cleanup_exclusions()protecting.vscode/settings.json, plus executable-bit restoration on upgrade) out into its own PR (fix: preserve .vscode/settings.json and script +x bit on integration upgrade #3020) so this one is scoped purely to the converge command.The PR now contains only source-of-truth changes for the converge command: the command template (
templates/commands/converge.md), core-command registration acrosssrc/specify_cli/, the integration test updates, and the README Core Commands entry.Testing
uv run specify --helpuv sync && uv run pytestPost-consolidation validation (2026-06-17, GitHub Copilot / Claude Opus 4.8, macOS/zsh)
Re-validated after folding in #3003/#3005, removing non-source scaffolding/artifacts, splitting out the unrelated upgrade fix, and rebasing on
main:Automated:
uv run python -m pytest tests/test_agent_config_consistency.py tests/integrations -q→ 2410 passed, 1 skipped (the suites that enumerate the core command set, now includingconverge). Claude argument-hint regression (from Guard Claudeconvergeskill against unsupported argument hints #3005) passes; noconvergeentry remains in Claude argument hints.Behavioral — scaffolded a fresh project from this branch (
specify init --integration copilot) with a small real feature (slugify, FR-004 deliberately unimplemented) and executed theconverge.mdworkflow:## Phase 3 — Convergencewith tasks tracing toFR-004 (missing)/SC-002 (missing); correct phase + ID numberingspec.md/plan.md/source byte-for-byte unchanged;tasks.mdappend-only, existing tasks intacttasks.mdnot modified (no empty header)tasks.mdFeature resolution: confirmed only
SPECIFY_FEATURE_DIRECTORY+.specify/feature.jsonare used (no branch-prefix fallback), matching the corrected docs.Earlier validation also covered sample-project installs across
--integration copilot/--integration gemini, template-token resolution (no leftover{SCRIPT}/__SPECKIT_COMMAND_*__), and a full manual quickstart pass across the six scenarios.AI Disclosure
The command template, core-command registration edits, and SDD work were authored with GitHub Copilot (model: Claude Opus 4.8) on behalf of @BenBtg, who reviewed the changes. The feature was itself built using the Spec Kit spec-driven workflow (specify → plan → tasks → implement); the agent also ran the automated test suite and the manual/behavioral validation.